DOCSP-41963: Databases and collections #136
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for docs-php-library ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
mongoKart
requested changes
Sep 11, 2024
source/databases-collections.txt
Outdated
| Dropping a collection from your database permanently deletes all | ||
| documents and all indexes within that collection. | ||
|
|
||
| Drop a collection only if the data in it is no longer needed. |
There was a problem hiding this comment.
S:
Suggested change
| Drop a collection only if the data in it is no longer needed. | |
| Drop a collection only if you no longer need the data in it. |
source/databases-collections.txt
Outdated
| :end-before: end-create-collection | ||
|
|
||
| You can specify collection options, such as maximum size and document | ||
| validation rules, by passing them as an array parameter to ``createCollection()``. |
There was a problem hiding this comment.
S:
Suggested change
| validation rules, by passing them as an array parameter to ``createCollection()``. | |
| validation rules, by passing them as an array to the ``createCollection()`` method. |
source/databases-collections.txt
Outdated
| **write concern**. | ||
|
|
||
| By default, databases inherit read and write settings from the ``MongoDB\Client`` | ||
| instance, and collections inherit them from the database. However, you can change |
There was a problem hiding this comment.
Suggested change
| instance, and collections inherit them from the database. However, you can change | |
| instance, and collections inherit them from the database. You can change |
source/databases-collections.txt
Outdated
| concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-readconcern>`__ | ||
| in the extension API documentation. | ||
| - ``writeConcern``: Sets the write concern. For a list of available write | ||
| concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ |
There was a problem hiding this comment.
Suggested change
| concerns, see `MongoDB\\Driver\\ReadConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ | |
| concerns, see `MongoDB\\Driver\\WriteConcern <{+php-manual+}/class.mongodb-driver-writeconcern>`__ |
source/databases-collections.txt
Outdated
|
|
||
| .. tip:: | ||
|
|
||
| To learn more about the read and write settings, see the following guides in the |
There was a problem hiding this comment.
Suggested change
| To learn more about the read and write settings, see the following guides in the | |
| To learn more about read preferences and read and write concerns, see the following guides in the |
source/databases-collections.txt
Outdated
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| The following example shows how to set the read preference, read concern, and | ||
| write preference of a database called ``test_database`` by passing an options |
There was a problem hiding this comment.
Suggested change
| write preference of a database called ``test_database`` by passing an options | |
| write concern of a database called ``test_database`` by passing an options |
source/databases-collections.txt
Outdated
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| The following example shows how to set the read preference, read concern, and | ||
| write preference of a collection called ``test_collection`` by passing an options |
There was a problem hiding this comment.
Suggested change
| write preference of a collection called ``test_collection`` by passing an options | |
| write concern of a collection called ``test_collection`` by passing an options |
source/databases-collections.txt
Outdated
Comment on lines
252
to
255
| By default, the library uses only those members whose ping times are within 15 milliseconds | ||
| of the nearest member for queries. To distribute reads between members with | ||
| higher latencies, pass an options array to the ``MongoDB\Client`` constructor that | ||
| sets the ``localThresholdMS`` option. |
There was a problem hiding this comment.
S: this might be slightly clearer
Suggested change
| By default, the library uses only those members whose ping times are within 15 milliseconds | |
| of the nearest member for queries. To distribute reads between members with | |
| higher latencies, pass an options array to the ``MongoDB\Client`` constructor that | |
| sets the ``localThresholdMS`` option. | |
| The library uses only those members whose ping times are within the local | |
| threshold of the nearest member for queries. By default, | |
| the local threshold is 15 milliseconds of latency. To distribute reads among members with | |
| higher latencies, pass an options array to the ``MongoDB\Client`` constructor that | |
| sets the ``localThresholdMS`` option. |
source/databases-collections.txt
Outdated
| :start-after: start-local-threshold | ||
| :end-before: end-local-threshold | ||
|
|
||
| In the preceding example, the {+php-library+} distributes reads between matching members |
There was a problem hiding this comment.
Suggested change
| In the preceding example, the {+php-library+} distributes reads between matching members | |
| In the preceding example, the {+php-library+} distributes reads among matching members |
mongoKart
requested changes
Sep 12, 2024
source/databases-collections.txt
Outdated
| the {+php-library+} reads from the nearest replica-set members, chosen according to | ||
| their ping time. | ||
|
|
||
| By default, the library only uses members whose ping times are within 15 milliseconds |
There was a problem hiding this comment.
Suggested change
| By default, the library only uses members whose ping times are within 15 milliseconds | |
| By default, the library uses only members whose ping times are within 15 milliseconds |
mongoKart
approved these changes
Sep 12, 2024
norareidy
requested review from
a team and
jmikola
and removed request for
a team
jmikola
reviewed
Sep 16, 2024
source/databases-collections.txt
Outdated
| cursor containing all collections in the database and their associated metadata. | ||
|
|
||
| The following example calls the ``listCollections()`` method and iterates over | ||
| the returned cursor to print the collections from the :ref:`php-db-coll-access-collection` |
There was a problem hiding this comment.
Suggested change
| the returned cursor to print the collections from the :ref:`php-db-coll-access-collection` | |
| the returned iterator to print the collections from the :ref:`php-db-coll-access-collection` |
Although the listCollections command returns a cursor, PHPLIB abstracts that with another iterator. This allows us to do things like cache the results and return typed model classes (e.g. CollectionInfo).
Caching is helpful if users want to iterate the result multiple times, as the original cursor can only be iterated once as it streams results from the server.
Also note that the special iterator classes returned by the database, collection, and index enumeration methods are being deprecated and will be removed in 2.0 (see: PHPLIB-1522). The individual result classes (e.g. CollectionInfo) will remain, though. In order to future-proof the docs, I propose we just talk about these methods returning an iterator.
source/databases-collections.txt
Outdated
Comment on lines
132
to
133
| For more information about iterating over a cursor, see the :ref:`php-cursors` | ||
| guide. |
There was a problem hiding this comment.
Suggested change
| For more information about iterating over a cursor, see the :ref:`php-cursors` | |
| guide. |
This can be removed since none of these enumeration methods return a cursor.
source/databases-collections.txt
Outdated
| instance, and collections inherit them from the database. You can change | ||
| these settings on your database by passing an options array to the | ||
| ``MongoDB\Client::selectDatabase()``. You can change these settings on your collection | ||
| by passing an options array to the ``MongoDB\Client::selectCollection()`` method. |
There was a problem hiding this comment.
Regarding collection inheritance, note that if users call Client::selectCollection() they would effectively inherit the Client's options since an interstitial Database object is never created.
Database::selectCollection() isn't even mentioned in this paragraph, although it was in a previous section. I'll note that the code example only demonstrates Database::selectCollection(), so perhaps you want to focus on that here instead of the Client method.
I'll defer to you if any of this requires some attention.
| // Lists the collections in the "test_database" database | ||
| // start-find-collections | ||
| foreach ($client->test_database->listCollections() as $collectionInfo) { | ||
| print_r($collectionInfo) . PHP_EOL; |
There was a problem hiding this comment.
I assume print_r() might be preferred here since var_dump() output is a bit messier.
| // end-drop-collection | ||
|
|
||
| // Sets read and write settings for the "test_database" database | ||
| // start-database-settings |
There was a problem hiding this comment.
I noticed the RST doesn't talk about specifying any of these options on the client by way of the connection string. Is that to be covered by some other tutorial?
source/includes/databases-collections/databases-collections.php
Outdated
Show resolved
Hide resolved
source/includes/databases-collections/databases-collections.php
Outdated
Show resolved
Hide resolved
source/includes/databases-collections/databases-collections.php
Outdated
Show resolved
Hide resolved
jmikola
reviewed
Sep 17, 2024
| @@ -63,13 +72,15 @@ | |||
|
|
|||
| // end-collection-settings | |||
|
|
|||
| // Instructs the library to prefer New York data center reads using a tag set | |||
| // Instructs the library to prefer reads from secondary replica set members | |||
| // located in New York but fall back to those in San Francisco | |||
There was a problem hiding this comment.
Suggested change
| // located in New York but fall back to those in San Francisco | |
| // located in New York, followed by a secondary in San Francisco, and | |
| // lastly fall back to any secondary. |
This captures the effect of the empty tag set.
Please adjust the RST paragraph above this code example accordingly. If you want to borrow some language from the existing server manual, there's a nicely worded tip in Order of Tag Matching.
jmikola
approved these changes
Sep 17, 2024
5 tasks
norareidy
added a commit
that referenced
this pull request
Sep 27, 2024
* Add PR template * Scaffolding * DOCSP-41953: Create a deployment (#93) * DOCSP-41953: Create a deployment * toc * add troubleshoot file * DOCSP-41954: Create a connection string (#99) * DOCSP-41954: Create a connection string * edits * spacing * DOCSP-42388: Next steps (#101) * DOCSP-41975: Retrieve data (#102) * DOCSP-41975: Retrieve data * fixes * quotes * code fix * JS feedback * JT feedback * code format * fix * JT feedback 2 * edit * DOCSP-41952: Download and Install (#92) * DOCSP-41952: Download and Install * edits * toc, fixes * AS feedback * AS feedback 2 * typo * JT feedback * DOCSP-41976: Projection guide (#104) * DOCSP-41976: Projection guide * edits * fixes * code edits, output * JS feedback * JT feedback * DOCSP-41955: Connect to MongoDB (#100) * DOCSP-41955: Connect to MongoDB * edits * edit * RR feedback * typo * code edit * DOCSP-41974: Specify a query (#103) * DOCSP-41974: Specify a query * edits * output * fix * snooty.toml * RR feedback * code edits * DOCSP-41977: Specify documents to return (#105) * DOCSP-41977: Specify documents to return * edits * code output * toc * MM feedback, code edits * edit * JT feedback * edit * test * MM feedback 2 * DOCSP-41957 - Mongo Client (#106) Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> * DOCSP-41960 - TLS (#114) * DOCSP-41978: Count documents (#108) * DOCSP-41978: Count documents * edits * code ex format * link * RR feedback * DOCSP-41979: Distinct values (#109) Adds a Distinct Values guide. * DOCSP-41981: Change streams (#113) Adds a Change Streams guide. * DOCSP-41993 Compatibility Table * test webhook * toc and sharedincludes * lang table * edits * headings * retry on shared include * shared includes * callout * help links * DOCSP-41958 - Connection Targets (#107) Co-authored-by: Nora Reidy <nora.reidy@mongodb.com> Co-authored-by: Andreas Braun <git@alcaeus.org> * tech review * DOCSP-41968: Update documents (#118) * DOCSP-41968: Update documents * snooty fix * edits * DOCSP-41967: Insert documents (#116) * DOCSP-41967: Insert documents * build * snooty * edit * JS feedback * JT feedback * JT feedback 2 * DOCSP-41980: Cursor guide (#110) * DOCSP-41980: Cursor guide * edits * code edits * output * vale fix * MM feedback * edit * fix code ex * edit * JT feedback * DOCSP-41988: Aggregation (#115) * DOCSP-41988: Aggregation * toc * edits * code edit * JS feedback * dev center * JM feedback * explain api link * JM feedback 2 * DOCSP-41983: indexes landing pg * wip * wip * MM PR fixes 1 * JM tech review 1 * JM tech review 1 * wip * wip * DOCSP-41969: Replace documents (#125) * DOCSP-41969: Replace documents * edits * wording * SA * JT feedback * JM tech review 2 * Add files via upload * DOCSP-41970: Delete documents (#128) Adds a guide that shows how to delete documents. * DOCSP-41984: single field index * wip * JS PR fixes 1 * wip * DOCSP-41986: multikey indexes * links * bullet pts * JS suggestion * fix whitespace per JM comment * uncomment * DOCSP-41985: compound idx * small fix * DOCSP-41966: Write operations landing (#135) * DOCSP-41966: Write operations landing * edits * RR feedback * JT feedback * JT feedback 2 * gridfs examples * DOCSP-42026: In use encryption (#142) * DOCSP-42026: In use encryption * edit * DOCSP-41972: GridFS guide (#133) * DOCSP-41972: GridFS guide * fixes * code edits * fix * RR feedback * phpmethod * fix * JM most feedback * alternate upload/download methods * file revisions * code fix * tojson * edits * JM feedback 2 * edits * JM last feedback * DOCSP-41971: Bulk write (#130) * DOCSP-41971: Bulk write * edits * JS feedback * api links * DOCSP-41987: atlas search idx * resolve todos * toc * DOCSP-41963: Databases and collections (#136) * DOCSP-41963: Databases and collections * edits * phpmethod * code fix * MW feedback * fix * MW feedback 2 * JM feedback * JM feedback 2 * JS fix * internal review * DOCSP-41982: cluster monitoring * small fixes * MW PR fixes 1 * test netlify * spacing * try using out of repo ref and add back legend * ou of repo ref * legend glitch * JM tech review 1 * single quotes * links * vale * remove older driver version past 1.15 * DOCSP-41991 What's New * add rest of versions * fix links * fix links * JM tech review 2 * DOCSP-41964: Time series collections (#138) * DOCSP-41964: Time series collections * toc * edits * keywords * SA feedback * JT feedback * JM final fixes * review comments * typo * DOCSP-41973 Read Landing Page * review comments * vale errors * small thing * full page with ex * add page * meta * DOCSP-41965: Read and write settings (#146) * DOCSP-41965: Read and write settings * more info * edits * edits * headers * fix link * fix * RR feedback * api docs * fix * fix * DOCSP-41950: Landing page (#150) * DOCSP-41950: Landing page * fix build errors * fixes, data formats * toc * fix * data formats folder * RR feedback * fix * remove file * edit sample app intro * change links in count sections * update sample app intro * DOCSP-41990: Authentication mechanisms (#139) * DOCSP-41990: Authentication mechanisms * client tabs * edits * edits * add info * reduce repetition * add section * fix link * MW feedback * fix * JM most feedback * move to code file * more JM edits * JM feedback 2 * DOCSP-41989: Security landing page (#149) * DOCSP-41989: Security landing page * more info * edits * snooty.toml * edits * RR feedback * JM feedback * DOCSP-41962 - Stable API (#117) Co-authored-by: Jeremy Mikola <jmikola@gmail.com> * DOCSP-41992 Upgrade versions * toc * edits * how to upgrade sections * style * edit * edit * review comments * ref * Revise descriptions for server opening/closed events * DOCSP-43204: Connection landing page (#147) * DOCSP-43204: Connection landing page * toc edit * edits * remove compression * fix * sample app * snooty * JM feedback * replica set * JM feedback 2 * JM last feedback * DOCSP-43819: php 1.20 release * fix * DOCSP-41956: run a command * wip * formatting fix * JS PR fixes 1 * link fix * style fixes * JT tech review 1 * wip * JM tech review * tree * api links * links * JM tech review 2 * small fixes * add ext upgrade command * DOCSP-41995: transaction * wip * update code * NR PR fixes 1 * wip * add emphasis * add with_txn() method to api links * cxn string env * edit * JM tech review 1 * remove dupe sc * tech review * wrap fix * edit copy * DOCSP-41959 - Connection Options (#112) Co-authored-by: Nora Reidy <nora.reidy@mongodb.com> Co-authored-by: Jeremy Mikola <jmikola@gmail.com> * DOCSP-43396: Cleanup (#151) * DOCSP-43396: Cleanup * quickstart fix * code fixes * edit * snooty * edit * code output * build log errors * another build fix * add info * upgrade guide to landing * fix * driver mentions * RR feedback * build fix * build fix * php directives --------- Co-authored-by: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Co-authored-by: Lindsey Moore <lindsey.moore@mongodb.com> Co-authored-by: Andreas Braun <git@alcaeus.org> Co-authored-by: rustagir <rea.rustagi@mongodb.com> Co-authored-by: Brandon Ly <brandonly@lostcoding.com> Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request Info
PR Reviewing Guidelines
JIRA - https://jira.mongodb.org/browse/DOCSP-41963
Staging - https://deploy-preview-136--docs-php-library.netlify.app/databases-collections/
Self-Review Checklist